Codex 1UP 增强你的 Codex CLI 编程能力
本文面向正在用 Codex 写代码的你。用 10 分钟,把你的本地终端升级成“能读、能改、能跑”的 AI 结对程序员,再配上一套结构化重构与语义 Diff 的硬核工具链。

为什么是 Codex 1UP?
Section titled “为什么是 Codex 1UP?”Codex 1UP 是一个一键增强包:给 OpenAI 的 Codex CLI 装上“外设”,把日常开发里最常用的查找、重构、对比、选择器都配齐,还顺手生成 AGENTS.md 规范和别名。它的定位很清晰——**让本地 Codex 更实战、更稳。**源仓库在 GitHub,近期活跃更新,支持 macOS / Linux,Windows 建议走 WSL。
它做了几件对程序员很“顶”的事:
- 一键装好 Codex CLI(@openai/codex),终端里直接召唤 AI 读改跑你的项目。
- 加装 ast-grep:按语法树做精准重构,不再被脆弱的纯文本 grep 绑架。
- 加装 difftastic 语义 Diff:审查 AI 改动时更清楚、少噪声。找不到就回退到 delta。
- 打包 fd / ripgrep / fzf / jq / yq:快速找文件、搜文本、模糊挑选、切 JSON/YAML。
- 内置 AGENTS.md 模板与多种配置档(SAFE / DEFAULT / YOLO),开箱可用,还能按团队风格微调。
- 要在大仓里安全重构:比如批量把老接口替换成新 SDK,ast-grep + Codex 能先“规划后执行”,再用 difftastic 审改。
- 刚接手遗留项目:
rg秒级摸清“这个函数被谁调”,fd找文件比find快很多,fzf交互选目标。 - 注重合规和可控:选 SAFE/DEFAULT 模式,限制越权与外网访问;需要全速就切 YOLO,但要知道自己在做什么。
- 团队要统一 AI 使用规范:AGENTS.md 一键模板,约定“先用 fd/rg,命中多再 fzf,结构化改动交给 ast-grep”。
一图看亮点(文字小结)
Section titled “一图看亮点(文字小结)”- 读改跑:Codex CLI 本地运行,可读文件、编辑与执行任务,支持用 ChatGPT 账号登录。
- 结构化重构:
ast-grep -p 'old()' -r 'new()'这类“像写代码一样写模式”。 - 语义审改:
cxdiff走 difftastic,让“真正的改动”一目了然。 - 搜与选:
rg查文本、fd找文件、fzf模糊挑选;jq/yq处理 JSON/YAML 配置。
实战安装与过程解读(基于你的 dry-run)
Section titled “实战安装与过程解读(基于你的 dry-run)”你提供的执行记录如下(dry-run:只打印将会发生的事,不改动系统):
git clone https://github.com/openai/codex-1up.git
cd codex-1up
./install.sh --dry-run==> codex-1up installerLog: /Users/vs/.codex-1up/install-20250910-174058.log✔ Node.js present (v22.11.0)Checking global npm packages (@openai/codex, @ast-grep/cli)✔ @openai/codex up-to-date (0.31.0)✔ @ast-grep/cli up-to-date (0.39.5)✔ Global npm packages are up-to-date✔ Codex CLI installed✔ ast-grep installedDetected package manager: brew[dry-run] brew update[dry-run] brew install fd ripgrep fzf jq yq difftastic⚠ difftastic not found and Rust/cargo missing; falling back to git-delta✔ rg ✓✔ jq ✓✔ ast-grep ✓Configure git diff tools for better syntax-aware code diffs (recommended for developers)? [y/N] yConfiguring git difftool aliases⚠ No difftastic or delta found; git diff will remain defaultThe following aliases will be added to /Users/vs/.zshrc: cx='codex exec' # Run codex commands cxdiff='git difftool -y' # Launch git difftool fd='fdfind' # fd-find alias (if applicable)Add these aliases to your shell config? [y/N] yUpdating shell rc: /Users/vs/.zshrc[dry-run] append block to /Users/vs/.zshrcChoose your codex-1up configuration profile:
1) SAFE - Most restrictive, asks for approval when commands fail (Recommended for high-security environments)
2) DEFAULT - Balanced approach, asks for approval when needed (Recommended for most users - good security/usability balance)
3) YOLO - Full access, never asks for approval ⚠️ WARNING: Allows codex full disk + network access! ⚠️ WARNING: Inherits ALL environment variables (including secrets)! ⚠️ Only use in trusted, sandboxed environments!
4) NO CHANGES - Do not create or modify ~/.codex/config.toml (You can manage it yourself later)Choose profile [1-4] (default: 2/DEFAULT): 2⚠ ~/.codex/config.toml already existsOverwrite with the 'default' template? (existing will be backed up) [y/N] y[dry-run] cp /Users/vs/.codex/config.toml /Users/vs/.codex/config.toml.backup.20250910_174210Backed up existing config to: /Users/vs/.codex/config.toml.backup.20250910_174210Creating config using default profile[dry-run] cp /Users/vs/WorkSpaces/VibeSparking/github/regenrek/codex-1up/templates/configs/codex-default.toml /Users/vs/.codex/config.toml✔ Created ~/.codex/config.toml with default profileSee config options: https://github.com/openai/codex/blob/main/docs/config.mdDo you want to create a global AGENTS.md for personal guidance at ~/.codex/AGENTS.md?
1) default - Generic rubric (works for most repos) 2) typescript - TS/TSX-focused rubric with ast-grep examples 3) python - Python-focused rubric and tooling notes (ruff, mypy, pytest) 4) shell - Shell/Bash-focused rubric with shellcheck/shfmt/bats tips 5) NONE - Do not create ~/.codex/AGENTS.mdChoose template [1-5] (default: 5/NONE): 1Writing global AGENTS.md to: /Users/vs/.codex/AGENTS.md (template: default)[dry-run] cp /Users/vs/WorkSpaces/VibeSparking/github/regenrek/codex-1up/templates/agent-templates/AGENTS-default.md /Users/vs/.codex/AGENTS.md✔ Wrote /Users/vs/.codex/AGENTS.mdVS Code extension id not provided. Use: --vscode <publisher.extension>✔ All done. Open a new shell or 'source' your rc file to load aliases.Next steps: 1) codex # sign in; then ask it to plan a refactor 2) ./bin/codex-1up agents --path /Users/vs/WorkSpaces/VibeSparking/github/regenrek/codex-1up # write a starter AGENTS.md to your repo 3) Review ~/.codex/config.toml (see: https://github.com/openai/codex/blob/main/docs/config.md)逐行要点解释:
- Node / 全局包检查:确认有 Node 22,并核对
@openai/codex与@ast-grep/cli的版本;你的机器均为最新。Codex CLI 是官方维护的本地编码 Agent。 - 包管理器识别为 Homebrew:将安装
fd / ripgrep / fzf / jq / yq / difftastic。这几个工具分别负责“找文件、搜文本、模糊选择、JSON、YAML、语义 Diff”。 - difftastic 提示:由于缺少 Rust/cargo,脚本计划回退到 git-delta;dry-run 模式下只打印不执行。difftastic 是“懂语法”的 Diff。
- Git difftool 与别名:
cxdiff走git difftool -y,cx等于codex exec。方便一键审改与批量跑命令。 - 配置档选择:你选了 DEFAULT,即“默认平衡”——工作区可读改跑,对越权/外网会询问。更保守可选 SAFE,更解放可选 YOLO。
- 自动备份并写入
~/.codex/config.toml:用模板生成,随时可手改。官方文档也建议先跑codex登录 ChatGPT 账号。 - 创建全局
~/.codex/AGENTS.md:你选了 default 模板,给 Codex 一个“如何选工具”的行为指南。 - Next steps:打开新终端或
source ~/.zshrc生效别名 → 运行codex登录 → 在项目里写入仓库级 AGENTS.md。
小贴士:Windows 建议在 WSL 里跑 Linux 路线;官方对 Windows 支持仍以 WSL 为佳。
快速上手 5 招(直接可抄)
Section titled “快速上手 5 招(直接可抄)”-
让 Codex 先“打谱”再动手
codex "Plan a refactor to replace axios with fetch; then apply and run tests" -
结构化替换(TS 项目示例)
ast-grep -p "oldApi($A)" -r "newApi($A)" src --lang ts -
秒搜调用点
rg "useAuth(" -n/fd "auth*.ts"/git grep之外更快更准。 -
审改用语义 Diff
cxdiff打开 difftastic(若已装),更聚焦“真实语义变化”。 -
批处理配置
jq '.scripts' package.json/yq '.services[].image' docker-compose.yml。
风险与最佳实践
Section titled “风险与最佳实践”- YOLO 档真的很猛:默认放开读写与网络,别在含有敏感环境变量的生产机上用。
- 大变更必审:用
cxdiff+ 单元测试兜底,必要时拆小 PR。 - AGENTS.md 要“贴合你们的 repo”:给出正例/反例,标注“何时用 ast-grep,何时只读规划”。
Codex 1UP = 本地 Codex + 结构化工具链。 写得更快,改得更稳,看得更清楚。 如果你正准备给团队引入 AI 结对,这套组合拳,值得今天就装上试试。
你觉得最离不开的是哪一个工具?有没有被 ast-grep 或 difftastic 救过命的故事?欢迎在评论区聊聊。











































































































































































